API 使用指南

Medusa 為多模型 API 服務之工具，包含 API 中介層（Tier 2）和 LLM 推論加速器（Tier 3）。
此服務整合API 代理伺服器（Tier 2）與LLM 推論加速器（Tier 3），提供標準化 API 介面並串接多種開源模型，您可透過 API 租用方式快速建立 LLM 應用服務。
只需使用 Lightweight-API 介面，您便可以輕鬆管理您的 API 服務狀態與 API 金鑰。

Lightweight-API基本介紹

Lightweight-API 是一個與 OpenAI 相容的 API 服務，允許使用者透過Lightweight-API Portal訪問 多模型API服務 上的多種模型。

登入服務

1. 開啟入口網頁（ https://portal.genai.nchc.org.tw/login ）
2. 點選 iService 登入，並登入 iService 帳號。

   若無 iService 帳號，請先至 iService 網站 申請帳號。

3. 自計畫列表選擇欲使用的計畫，點選前往計畫。

   若無可用計畫，請參照 iService 申請計畫/專案說明 申請計畫。
   請確認計畫已開通使用本服務。

4. 成功登入後，即可看到該計畫中的可用額度、Lightweight-API 金鑰列表、模型列表等基本資訊。
5. 欲登出本服務，請點選右上角之帳號圖像，呼叫下拉式選單後點選登出。

功能與 Lightweight-API Portal 使用說明

在 Lightweight-API Portal 上，使用者可以查看 iService 上已擁有的計畫，包含每個計畫的使用餘額。每個計畫中提供 Lightweight-API 金鑰的管理功能，使用者可以在此新增、修改或查看 Lightweight-API 金鑰的狀況，以確保訪問權限的安全性和便利性。

• 查看計畫：登入 Lightweight-API Portal 後，可以清楚查看自己在 iService 上擁有的計畫及各計畫的餘額狀態。
• Lightweight-API 金鑰管理：每個計畫中提供 Lightweight-API 金鑰的管理功能，用戶可以生成新的 Lightweight-API 金鑰、修改現有的金鑰設定，或查看 Lightweight-API 金鑰的狀況，以便於管理和使用。

Lightweight-API 金鑰管理

參照登入服務成功登入後，於登入後首頁點選API入口，即可進入 Lightweight-API 金鑰的管理頁面。
在這個頁面中，您將會看到計劃中的 Lightweight-API 金鑰的詳情，其中包含名稱、使用的頻率限制、當前使用量、可用上限、有效時間及建立時間等資訊，並且可以針對各金鑰進行管理操作。

API 使用說明

取得 Lightweight-API 金鑰後，使用者便可利用 Lightweight-API 存取「多模型API服務」提供的各類模型。詳細的 API 使用方法將會在API功能介紹中介紹，包括使用範例、請求格式、回應結構等，方便使用者快速上手。

其他功能

1. 欲切換 UI 介面的「Light」/「Dark」模式，請點選左下角的 ☀️ / 🌙 圖標呼叫選單，並點選欲設置的選項。

2. 登入後，可於右上角查看目前登入的使用者之名稱、權限（計畫建立者/計畫管理者/計畫使用者），並且在點選右方帳號圖像時，可確認使用者的名稱及電子信箱。

注意事項

• 帳號安全：請妥善保管 iService 登入資訊及 Lightweight-API 金鑰，確保帳號和 Lightweight-API 使用的安全性。
• 使用規範：請依照 Lightweight-API Portal 上的使用規範及說明文件，正確使用 Lightweight-API 資源。如有使用限制或流量規範，請參考相關說明。

API功能介紹

本章節介紹 Lightweight-api 提供的四個主要 API 功能，包含Models、 Completions、Chat Completions 和 Embeddings，說明各 API 格式的基本結構和用途。

目錄

• Models
• Completions
• Chat Completions
• Embeddings

---

Models

概述

Models API 用於查看 Lightweight-api 提供的模型列表和其特性。此 API 允許使用者查詢可用模型的相關資訊，適合選擇不同應用需求的模型。

請求格式

Endpoint: /v1/models

HTTP 方法: GET

範例請求:

curl -X 'GET' "https://portal.genai.nchc.org.tw/api/v1/models" \
-H "x-api-key: <您的API KEY>" \
-H 'Content-Type: application/json'

回應格式

• data：包含模型列表，每個模型包含 id、object、created 等屬性，提供模型的詳細資訊。

---

Completions

概述

Completions API 用於生成完成給定提示的文本，適合用於內容生成、回答問題等需要簡單文本生成的應用。

請求格式

Endpoint: /v1/chat/completions

HTTP 方法: POST

範例請求:

curl -X POST "https://portal.genai.nchc.org.tw/api/v1/chat/completions" \
-H "x-api-key: <您的API KEY>" \
-H "Content-Type: application/json" \
-d '{
    "model": "Llama3-TAIDE-LX-8B-Chat-Alpha1",
    "messages": [
        {
            "role": "system",
            "content": "You are a helpful assistant. 你是一個樂於助人的助手。"
        },
        {
            "role": "user",
            "content": "請寫一篇小說"
        }
    ],
    "max_tokens": 20,
    "temperature": 0
}'

• model：指定使用的模型名稱。
• prompt：作為輸入的提示文本，模型將根據此文本生成回應。
• temperature (可選)：控制回應的隨機性。
• max_tokens (可選)：生成回應的最大字數。

回應格式

• choices：包含生成的回應列表，每個回應包含 text 和 finish_reason 屬性。
• usage：包含此次請求的 token 使用量統計。

---

Chat Completions

概述

Chat Completions API 用於生成對話式回應，適合聊天機器人等需要多輪對話的應用。此 API 使用模型來根據給定的對話歷史生成符合上下文的回應。

請求格式

Endpoint: /v1/chat/completions

HTTP 方法: POST

範例請求:

curl -X POST "https://portal.genai.nchc.org.tw/api/v1/chat/completions" \
-H "x-api-key: <您的API KEY>" \
-H "Content-Type: application/json" \
-d '{
    "model": "Llama3-TAIDE-LX-8B-Chat-Alpha1",
    "messages": [
        {
            "role": "system",
            "content": "You are a helpful assistant. 你是一個樂於助人的助手。"
        },
        {
            "role": "user",
            "content": "請寫一篇小說"
        }
    ],
    "max_tokens": 20,
    "temperature": 0
}'

• model：指定使用的模型名稱。
• messages：包含對話歷史的列表，每個訊息需包含 role 和 content 屬性。角色 (role) 可為 user、assistant 或 system，分別表示使用者、助理和系統指令的內容。
• temperature (可選)：控制回應的隨機性。範圍通常在 0 到 1 之間，值越高回應越隨機，值越低回應越保守。
• max_tokens (可選)：限制回應中的最大字數，以避免生成過長的回應。

回應格式

• choices：包含生成的回應列表，每個回應包含 message 和 finish_reason 屬性。
• usage：包含此次請求的 token 使用量統計，分別顯示 prompt 和 completion 的 token 數量。

---

Embeddings

概述

Embeddings API 用於將文本轉換成向量表示，適合語意相似度分析、推薦系統等應用。每段文本會生成一組高維向量來表示其特徵。

請求格式

Endpoint: /v1/embeddings

HTTP 方法: POST

範例請求:

curl -X POST "https://portal.genai.nchc.org.tw/api/v1/embeddings" \
-H "x-api-key: <您的API KEY>" \
-H "Content-Type: application/json" \
-d '{
    "model": "chatfire/bge-m3:q8_0",
    "input": "你好"
}'

• model：指定使用的模型名稱。
• input：需要轉換成向量的文本或文本列表。

回應格式

• data：包含生成的向量列表，每個向量包含 index 和 embedding 屬性。
• usage：包含此次請求的 token 使用量統計。

---

注意事項

• API Key：使用每個 API 需提供有效的 API Key，確保具備適當的訪問權限。
• Rate Limiting：每個 API 使用可能受到頻率限制，請參考 API Portal 的限制說明。
• Error Handling：若請求格式錯誤或資源不足，API 將返回錯誤代碼和訊息，請根據錯誤說明進行修正。